API Specification

RoleFerry Platform v1

---

1. Introduction

This document provides a detailed specification for the RoleFerry REST API v1. The API is designed to be RESTful, with predictable resource-oriented URLs, and uses JSON for all requests and responses.

2. Authentication

The RoleFerry API uses JWT Bearer tokens for authentication. All requests must include an Authorization header with a valid JWT:

Authorization: Bearer <your_jwt>

Access tokens have a short lifespan (15 minutes). When an access token expires, you must use a refresh token to obtain a new one. Refresh tokens are valid for 30 days.

3. Versioning

The API is versioned via the URL. The current version is v1:

https://api.roleferry.com/v1/

4. Rate Limiting

The API is rate-limited to 60 requests per minute per user. Exceeding this limit will result in a 429 Too Many Requests error. The following headers are included in each response:

X-RateLimit-Limit: The maximum number of requests per minute.
X-RateLimit-Remaining: The number of requests remaining in the current window.
X-RateLimit-Reset: The time (in UTC epoch seconds) when the rate limit will reset.

5. Idempotency

To prevent accidental duplicate requests, all POST requests support an Idempotency-Key header. If a request is received with the same idempotency key as a previous request, the original response will be returned without re-processing the request.

6. Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. All error responses include a JSON body with the following format:

{
  "error": {
    "code": "invalid_request",
    "message": "The `job_id` field is required."
  }
}

7. Endpoints

Users

GET /v1/users/me

Retrieves the currently authenticated user.

Jobs

GET /v1/jobs

Retrieves a list of jobs, with optional filtering.

GET /v1/jobs/{id}

Retrieves a specific job by its ID.

Applications

GET /v1/applications

Retrieves a list of applications for the current user.

POST /v1/applications

Creates a new application.

Outreach

POST /v1/outreach/send

Sends a personalized email to a contact.

8. Webhooks

The API can send webhooks to a pre-configured URL to notify your application of events. All webhooks are sent as POST requests with a JSON body.

Events

application.created
email.sent
email.opened
email.replied

9. Changelog

v1.0 (Current) - Q1 2026

Initial release of the RoleFerry API.

10. Deprecation Policy

We will provide at least 6 months' notice before deprecating any part of the API. Deprecated endpoints will return a Warning header. After the deprecation period, the endpoints will be removed.

RoleFerry Documentation